Skip to content

Add object lifetime and reference tracking documentation - #2460

Merged
Sergio Pedri (Sergio0694) merged 2 commits into
staging/3.0from
user/sergiopedri/memory-management-doc
Jul 21, 2026
Merged

Add object lifetime and reference tracking documentation#2460
Sergio Pedri (Sergio0694) merged 2 commits into
staging/3.0from
user/sergiopedri/memory-management-doc

Conversation

@Sergio0694

Copy link
Copy Markdown
Member

Summary

Add a documentation guide describing how CsWinRT 3.0 manages the lifetime of projected Windows Runtime objects across the three systems involved: the .NET garbage collector, COM reference counting, and the XAML reference tracker.

Motivation

CsWinRT bridges three independent lifetime-management systems, and getting their interaction right is subtle (COM aggregation, tear-off interfaces, and reference-tracker cycles in particular). There was previously no conceptual reference for this in the 3.0 docs. This guide gives contributors an accurate mental model of how RCWs, CCWs, and reference tracking work, grounded in the current WinRT.Runtime2 implementation.

The content is adapted from the never-merged memory management doc (PR #899), which targeted CsWinRT 2.x and had accumulated unresolved review feedback. It has been rewritten to match the actual CsWinRT 3.0 runtime and to incorporate that feedback.

Changes

  • docs/memory-management.md: new guide covering COM reference counting for RCWs (projected types deriving from WindowsRuntimeObject, with native objects owned by free-threaded and context-aware WindowsRuntimeObjectReference instances, plus GC memory pressure and agility), CCWs created through WindowsRuntimeComWrappers, COM aggregation for managed types extending unsealed Windows Runtime types, tear-off interface handling, and IReferenceTracker integration for XAML (including native/managed reference-cycle collection).
  • README.md: link the new guide from the "Getting started" documentation list.

Notes

  • All descriptions were verified against the WinRT.Runtime2 sources (the WindowsRuntimeObjectReference hierarchy, WindowsRuntimeObject, WindowsRuntimeComWrappers, and the object marshallers).
  • The review comments left on PR Memory management doc #899 were revisited; the valid ones (API links, acronym introductions, sectioning, the tear-off recommendation, and grammar/style) are addressed in this rewrite.

Add a guide describing how C#/WinRT 3.0 manages the lifetime of projected Windows Runtime objects across the .NET garbage collector, COM reference counting, and the XAML reference tracker. It covers RCWs (projected types deriving from WindowsRuntimeObject, with native objects owned by free-threaded and context-aware WindowsRuntimeObjectReference instances), CCWs created through WindowsRuntimeComWrappers, COM aggregation for types extending unsealed Windows Runtime types, tear-off interface handling, and IReferenceTracker integration for XAML, including native/managed reference-cycle collection.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add the new object lifetime and reference tracking guide to the documentation list in the repository README, following the existing docs cross-reference convention.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@Sergio0694
Sergio Pedri (Sergio0694) merged commit 7228284 into staging/3.0 Jul 21, 2026
11 checks passed
@Sergio0694
Sergio Pedri (Sergio0694) deleted the user/sergiopedri/memory-management-doc branch July 21, 2026 01:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CsWinRT 3.0 documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Documentation for C#/WinRT memory management

2 participants